# Overview

*gitlab-artifact-download* is a small tool for downloading an artifact created by a
[gitlab CI job](https://docs.gitlab.com/ce/ci/pipelines/job_artifacts.html).

The following actions can be run automatically after downloading the artifact:

* `deb_install`: install the specified deb package files
* *please suggest further useful actions*

The download occurs in a temporary directory by default.  A custom permanent location can also be
specified.


# Installation

Pick one of the following approaches:

* download the script: `wget https://notabug.org/sumpfralle/gitlab-artifact-download/raw/main/gitlab-artifact-download`
* install a [deb package](https://notabug.org/sumpfralle/gitlab-artifact-download/releases)


# Requirements

* [jq](https://github.com/stedolan/jq)
* [unzip](http://www.info-zip.org/UnZip.html)


# Usage

*gitlab-artifact-download* supports configuration either via a configuration file or via
environment variables.

## Run without configuration file

One-time operations may be executed by providing the relevant details via environment variables:

```shell
GITLAB_BASE_URL=https://gitlab.com \
    GITLAB_PROJECT=example/foo \
    GITLAB_AUTH_TOKEN=YOUR_PRIVATE_AUTH_TOKEN \
    GITLAB_JOB_NAME=deb_package \
    ACTIONS=deb_install \
    DEB_PACKAGE_NAMES="foo foo-dependencies" \
    gitlab-artifact-download install
```

## Run with a configuration file

The following example configuration specifies a download operation followed by the installation of
deb packages via `dpkg`:

```json
{
    "base_url": "https://gitlab.com",
    "project": "example/foo",
    "job_name": "deb_package",
    "auth_token": "YOUR_PRIVATE_AUTH_TOKEN",
    "actions": [
        "deb_install"
    ],
    "deb": {
        "package_directory": "build/debian",
        "package_names": [
            "foo",
            "foo-dependencies"
        ]
    }
}
```

This configuration file can be located in current directory or in the user's home directory as
`.gitlab-artifact-download.json`.

With the example configuration file above, the following call is sufficient:

```shell
gitlab-artifact-download install
```


# Runtime arguments

The following commands are supported:

* `install [REFERENCE]`: download and process the latest artifact for the given reference (commit ID, branch, tag or job ID; *REFERENCE* defaults to `main`)
* `list`: list the most recently built artifacts (including their expire date)
* `list-json`: list the most recently built artifacts (including their expire date, JSON format)
* `help`: a short overview


# Configuration

Most configuration settings (except for the location of the configuration file) can be specified
either via an environment variable or in a JSON-formatted configuration file.

The following precedence applies (the first match wins):

1. environment variable
2. setting in first configuration file
3. setting in second configuration file
4. ...


Environment variable | JSON path | Type | Required? | Description
-------------------- | --------- | ---- | --------- | -----------
`CONFIG_FILE` | - | string | no | Location of the configuration file to be loaded.  If this environment variable is undefined, then all files specified in `DEFAULT_CONFIG_FILES` are parsed (if they exist).
`DEFAULT_CONFIG_FILES` | - | space-separated filenames | no | Defaults to `.gitlab-artifact-download.json ~/.gitlab-artifact-download.json` (first: current directory, then user's home directory).
`GITLAB_BASE_URL` | `.base_url` | string | yes | The base URL of the gitlab instance (e.g. `https://gitlab.com`).
`GITLAB_PROJECT` | `.project` | string or integer | yes | The name of the project (including its groups) or the project ID.
`GITLAB_JOB_NAME` | `.job_name` | string | yes | The name of the gitlab CI job, which generates the artifacts.
`GITLAB_AUTH_TOKEN` | `.auth_token` | string | yes | A [gitlab access token](https://docs.gitlab.com/ee/api/README.html#authentication) (personal or project-related) with full `api` permissions (`read_api` is currently not sufficient, see [gitlab#296476](https://gitlab.com/gitlab-org/gitlab/-/issues/296476)).
`DOWNLOAD_DIRECTORY` | `.download_directory` | string | no | The content of the artifact archive is extracted to this directory, if it is specified. By default (if unset), the archive is extracted to a temporary directory, which is removed after processing.
`ACTIONS` | `.actions` | array of strings | no | Certain actions can be executed after the downloading and extracting the artifact archive.  See the list of supported actions below.


## Actions

Some actions accept additional configuration settings.  These are documented as the environment
variable name and the JSON path (see above).


### Deb package installation (`deb_install`)

* `DEB_PACKAGE_DIRECTORY` / `.deb.package_directory`: (optional) directory within the archive, which contains `*.deb` files
* `DEB_PACKAGE_NAMES` / `.deb.package_names`: list of package names to be installed


# License

*gitlab-artifact-download* is published under the [GPLv3](https://www.gnu.org/licenses/gpl-3.0.html) or later.
